home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / CODESMIT.ARJ / CS.DOC next >
Text File  |  1992-01-07  |  19KB  |  496 lines

  1.                       Welcome to CodeSmith 
  2.  
  3. CodeSmith is an application generator. It's goal is to provide 
  4. you the programmer with near instant complete single database, 
  5. multiple screen, network/signle user applications without writing 
  6. a line of code. This is done by designing a data screen with 
  7. CodeSmith's internal screen painter. Your design can be based on 
  8. all or part of an existing database, one or more previous designs 
  9. or you can begin from scratch. In any case CodeSmith will write 
  10. the programs to manage your new/old database.
  11.  
  12.                      THE SAMPLE APPLICATION
  13.  
  14. Your created application (we'll use the name SAMPLE) will be 
  15. optimized for rapid data entry, retrieval, and editing. Searches 
  16. may be based on up to 15 indexes plus a user defined temp index 
  17. if less than 15 are used. Standard navigation features like 
  18. next/previous record, Go To record #, top, bottom, first record, 
  19. last record and skip are automatically provided. Multiple screens 
  20. are simply accessed by PgDn/PgUp.
  21.  
  22. A view command allows you to switch from full screen mode to 
  23. browse mode where each record is on a single line. Function key 
  24. assignments for use when adding records are accessed from the 
  25. opening menu. The user may assign text strings to function keys 
  26. F3 thru F10. F2 will replicate the data contained in the last 
  27. record, like SET CARRY ON. Any field may be assigned to 
  28. automatically replicate itself. F-Key and Dupe Key settings are 
  29. saved in .MEM files and restored at program start up.
  30.  
  31. CodeSmith generates the full and complete source code for your 
  32. application design with no hidden libraries. The only 
  33. requirements are those needed by Clipper itself.
  34.  
  35. In addition to generating a complete application, you can also 
  36. generate code fragments; input/output screens and procedures to 
  37. create a database structure. A real useful tool when changing an 
  38. existing application or when you just need a screen.
  39.  
  40. An Ad Hoc report writer allows the user to make their own 
  41. columnar reports. 
  42.  
  43. A Label Maker is included to create mailing labels from your 
  44. database or free form. Labels are 3 for a Laser Printer and 1 up 
  45. for dot matrix. If using a laser printer please select the proper 
  46. printer. The label maker prints 30 characters to a line and uses 
  47. a 12cpi font. HP Series II and IID do not come with a built in 
  48. 12cpi font so 10cpi is compressed to 12cpi.
  49.  
  50. Both the label maker and report writer respect index order and 
  51. filter settings.  
  52.  
  53. Printer selection is available for 16 popular models including HP 
  54. Lasers. These values are stored in public memvars (see 
  55. sample.prg) and can be used for pitch changes in reports that you 
  56. may add later. These values are saved to CSPRINT.MEM and are 
  57. restored at program start up. 
  58.  
  59. Laser Utilities provides access to most of the HP Laser front 
  60. panel options from a menu. If you're lazy like me it's great to 
  61. do a form feed or change trays without leaving your chair. You 
  62. may also switch from portrait to landscape or make pitch and line 
  63. spacing changes prior to writing a report.
  64.  
  65.  
  66. Terminology:
  67.  
  68. Object: An item on the screen. Can be a field, text, box or line.
  69.  
  70. <X> Single letter command. Example: Type X to exit.
  71.  
  72.  
  73. File Naming Convention:
  74.  
  75. Prior to generating code you will be prompted to give your 
  76. application a name. The .dbf file it is to manage shares the same 
  77. name. Files unique to your application will be based on the first 
  78. 5 or 6 characters of the named application. In the following 
  79. example we will use the name SAMPLE. 
  80.  
  81. SAMPLE.CS1  - Your Screen Design 
  82. SAMPLE.CS2  - Index keys for this design 
  83.  
  84.  
  85. CodeSmith produces the following files:
  86.  
  87. SAMPLE.PRG      Main Menu
  88. SAMPLADD.PRG    Add Records
  89. SAMPLGET.PRG    Search/Edit Record
  90. SAMPLHLP.PRG    Help File
  91. SAMPLE.MAK      Rmake Make file      
  92. SAMPLE.LNK      Blinker Link File
  93. SAMPLE.RTL      RTlink Link File
  94. GO.BAT          Generic, used to compile and link application.
  95. CS.CH           Generic Header File. Contains system colors.
  96. CSGENRL.PRG     Generic Functions and Procedures
  97. CSLABEL.PRG     Generic Label Maker
  98. CSVIEW.PRG      Generic Browser
  99. CSREPORT.PRG    Generic Report Writer
  100. CSQBE.PRG       Generic Query by Example/Complex Filter Builder
  101. CSLOCKS.PRG     Networking Functions
  102.  
  103. These 'generic' files are produced the same way each time so 
  104. there is no problem in overwriting them in different sessions 
  105. provided you have not modified them. The networking functions in 
  106. cslock.prg are either real or dummys. If use choose networking 
  107. code you get the real functions, otherwise the functions just 
  108. return a logical .t.. In this way the source code for both 
  109. network and single user applications is the same and there is no 
  110. performance penalty when selecting single user code. This also 
  111. greatly simplifies changing from one to the other.
  112.  
  113.  
  114. SAMPLE.EXE will produce.
  115.  
  116. SAMPLE.DBF    (ONLY IF NEEDED)
  117. SAMPLE1.NTX to SAMPLE15.NTX (ONLY IF NEEDED) 
  118. SAMPLKEY.MEM   F3-F10 key assignments
  119. SAMPLDUP.MEM   Fields to Dupe in Add Mode (like SET CARRY ON)
  120. CSPRINT.MEM    Printer pitch control macros 
  121.  
  122.  
  123.                          GETTING STARTED
  124.                      WITH THE SCREEN PAINTER
  125.  
  126.  
  127. CURSOR/OBJECT MOVEMENT:
  128.  
  129. Cursor movement is done with the familiar arrow keys. 
  130.  
  131. To move an object, place the cursor on the object (or box 
  132. outline) and press <Enter>. Use the arrow keys to move the object 
  133. around and press <Enter> to anchor it in place. 
  134.  
  135. To move the entire screen, place the cursor anywhere NOT on an 
  136. object and outside of any box, then press <Enter>. Move and 
  137. anchor the screen as above.
  138.  
  139. To move the contents of a box, place the cursor inside a box 
  140. outline and press <Enter>, use the arrow keys to move the 
  141. contents around and press <Enter> to anchor in place.
  142.  
  143. <Ctrl> <Right Arrow> moves cursor to the next object,
  144. <Ctrl> <Left Arrow> moves cursor to the previous object.
  145.  
  146. SCREEN CONTROL:
  147. Ctrl PgDn/Ctrl PgUp will get you from one CodeSmith 
  148. screen/window/page to the next. By using multiple sceens, your 
  149. application can easily accomodate more fields than can be fit on 
  150. one screen. Also you may combine or merge several applications 
  151. provided a one to one relationship exists.
  152.  
  153. EDITING COMMANDS: May be issued from the keyboard or from the 
  154. main menu. 
  155.  
  156. <A>  ADD OBJECT:
  157. Select box, character, date, line, logical, memo, numeric, text 
  158. or User Defined. 
  159.  
  160. Box: Select box type.
  161.      Drag box from the cursor position, down and to the right.
  162.      Press <Enter> to anchor it in place. You may edit or           
  163.      reposition the box later. 
  164. Box Attributes: Select an optional color (more about colors 
  165. later).
  166.  
  167. Character, Date, Logical, Memo & Numeric:
  168. Field Attributes:
  169.  
  170. Name: Each database field needs a unique name.
  171.  
  172. Order: This is the sequence that the field will appear when 
  173. adding and editing.
  174.  
  175. Description: Field descriptions are used for column titles in 
  176. view/browse mode. The default is the field name. Take an extra 
  177. minute to give your fields a description in English, your 
  178. customers will appreciate it.
  179.  
  180. Length: Character and numeric field lengths must be entered.
  181. Date, Logical and Memo are automatically entered.
  182.  
  183. Picture: Optional- PICTURE clause entered without quotes.
  184.  
  185. Color GET: Optional-This is the color used for the field when
  186. in add or edit mode. Use this option when you want a COLOR 
  187. different from the system SETCOLOR() setting. CodeSmith sets the 
  188. system color to a manifest constant called colornorm (lower case 
  189. without quotes) contained in cs.ch and defined as 
  190. 'w+/b,gr+/rb,,,bg+/b'.
  191.  
  192. COLOR may be input using the pre-defined manifest constants 
  193. colornorm/colorrev or as literal string such as 'bg+/b' (with 
  194. quotes) or you may select colors from CodeSmith's visual color 
  195. picker by pressing F3.
  196.  
  197. If the COLOR thing is confusing, remember that it is an option 
  198. and may be ignored.             
  199.  
  200.  
  201. Color SAY: Optional-This is the color used for the field when
  202. in show mode. 
  203.  
  204. WHEN Clause: Optional- WHEN is new to 5.01 and is a pre-condition 
  205. expression which must be met before the cursor will be allowed to 
  206. enter the GET during a READ. For example, suppose we have a 
  207. character field CPHONE to be used to hold a company phone number. 
  208. We could skip this field if the COMPANY field was empty using the 
  209. syntax !EMPTY(m->company). The produced code would look like:
  210.  
  211. @ xx,yy get CPHONE WHEN !EMPTY(m->COMPANY)
  212.  
  213. m-> is used to distinguish the memory variable and the field 
  214. which share the same name. Memory variables are used rather than 
  215. modifying the fields directly which allows for abandoning changes 
  216. prior to a save.
  217.  
  218. VALID Clause: Optional- VALID is a post-condition expression 
  219. which must be met before the cursor will be allowed to leave the 
  220. GET during a read. 
  221. Example: @ xx,yy get m->amount VALID m->amount > 0. 
  222. In this example only numbers greater than 0 will be accepted.  
  223.  
  224. Example: @ xx,yy get m->state VALID state(@state)
  225. Here the condition which must be met is a function state(). 
  226. STATE() is generated whether it is used or not and can be found 
  227. in csgenrl.prg. It is a pop-up validation function containing 
  228. state and territory two letter abbreviations which is activated 
  229. when an incorrect state is entered. Notice the parameter is 
  230. passed to the function by reference, @state and therefore the m-> 
  231. is omitted.
  232.  
  233. After defining the FIELD it is redisplayed showing it's name plus 
  234. ascii character 176 to pad it to length. If the name exceeds the 
  235. length of the field it is truncated. For example a logical field 
  236. with the name badaddr with be displayed as 'b'. 
  237.  
  238. Line: Select line type from an ASCII chart.
  239.      Use the right arrow key to draw line.
  240.      Press <Enter> to save it. 
  241. Line Attributes: Select an optional color.
  242.  
  243.  
  244. Text: Type in desired text.
  245.       Press <Enter> to save.     
  246. Text Attributes: Select an optional color.
  247.  
  248.  
  249. USER DEFINED allows you to insert custom code directly into your 
  250. application. This may be a line of code up to 250 characters in 
  251. length. Typical uses are procedure or function calls or maybe a 
  252. calculated result to display on screen. You can display a memo on 
  253. screen e.g. MEMOEDIT(fieldname, t, l, b, r, .f., .f.) or anything 
  254. that can be expressed in 250 character. The uses are limited by 
  255. your imagination and needs. 
  256.  
  257. USER DEFINED Attributes: Currently we have three places where 
  258. your USER DEFINED CODE may be inserted.
  259.  
  260. 1) Add- When adding a record.
  261.  
  262. 2) GET- When editing a record. 
  263.  
  264. 3) Show- When displaying/showing a record.
  265.  
  266. Future editions will have many more insertion points such as 
  267. after a read in add or edit mode so that you may have multiple 
  268. screens and also in several locations in SAMPLE.PRG, the main 
  269. menu. Let me know what you want and I'll try to accommodate.
  270.  
  271. Order: This is the sequence that your code will be processed in 
  272. relation to your other fields. 
  273.  
  274. User Defined Fields are notated by the Greek letter µ (Mu) to 
  275. make them distinctive. 
  276.  
  277.  
  278. <C>  COPY OBJECT:
  279. Place the cursor on text, line, USER DEFINED FIELD or box outline 
  280. to be copied and press <C>. The copied (duplicated object) will 
  281. flash. Use arrows keys to move it into position the press <Enter> 
  282. to anchor it in place. Boxes are copied less contents. Duplicate 
  283. data fields are not allowed.
  284.  
  285.  
  286. <D>  DELETE OBJECT:
  287. Place the cursor on an object (for boxes use the outline), or 
  288. empty row to delete and press <D>. There is no undo so it is 
  289. suggested that you save your work <S> from time to time.
  290.  
  291.  
  292. <E>  EDIT OBJECT
  293. Place the cursor on the object or box outline you wish to edit 
  294. and press <E>. Boxes may be resized, text and lines and USER 
  295. DEFINED code may be modified and database field attributes except 
  296. data type may be altered. 
  297.  
  298.  
  299. <F>  Field Selection:
  300. Select additional fields not already on the screen. If the 
  301. current session began with a previous design (.CS1 file) or a 
  302. blank screen, a DBF file (<G> option) needs to be selected prior 
  303. to selecting fields. CodeSmith will check all windows for 
  304. duplicate fields. 
  305.  
  306.  
  307. <G> Get DBF file: 
  308. Choose a .DBF file from which fields may be selected.
  309.  
  310.  
  311. <I>  INSERT ROW:
  312. Well not exactly. Unlike a wordprocessor we cannot actually 
  313. insert a row but we can move all objects from the line containing 
  314. the cursor down one row provided the last line is empty.
  315.  
  316.  
  317. <L>  setMode():
  318. Change screen display to 25/43/50 lines; monitor and graphics 
  319. card permitting.
  320.  
  321.  
  322. <N>  New Screen File:
  323. Import a file, .DBF or a previous session saved as a .CS1 file. 
  324. If the current window contains data, the imported file will be 
  325. added to a new window. You may freely switch windows with the 
  326. Ctrl PgDn/Ctrl PgUp keys. Your application will access these 
  327. multiple screens, in order, using the PgDn/PgUp keys.  Note that 
  328. when importing a file, CodeSmith will not check for duplicate 
  329. fields! It is up to you to rename any duplicate fields prior to 
  330. application generation. This approach was taken in favor of 
  331. omitting or renaming the duplicate fields at import time. 
  332.  
  333.  
  334. <P>  Preview mode simulates the appearance of your application in 
  335. both show and add/edit modes. Your picture clauses and colors are 
  336. used but valids and whens are not. This will give you a good idea 
  337. what your finished screens will look like.
  338.  
  339. <R>  Redraw Screen:
  340. Use after overlapping an object if you see phantom characters.
  341.  
  342.  
  343. <S>  Save Work:
  344. Save your application design for future use. This is a database 
  345. file with a .CS1 (added for you) extension. Index keys and de
  346. scriptions are save to a file using the same name but a .CS2 
  347. extension. 
  348.  
  349.  
  350. <T>  Toggle Menu:
  351. Turn the main footer menu on/off.
  352.  
  353.  
  354. <X>  eXit to DOS
  355.  
  356.  
  357. <Z>  Zap Screen:  
  358. Clears Screen. Save your work first since there is no undo 
  359. feature!
  360.  
  361. Global Field Attributes:
  362.  
  363. COLORs, field order/numbers, PICTUREs VALIDs and WHENs may be 
  364. entered or modified for all fields at once. This is much faster 
  365. that editing each field and then remembering the individual 
  366. settings. I will usually input the bare necessities first and 
  367. then do my colors, field numbers, valids and whens here before 
  368. generating my application. 
  369.  
  370.  
  371. INDEX KEYS:
  372. CodeSmith allows up to 15 index keys and descriptions. Index keys 
  373. may be up to 250 characters and there is no syntax checking. This 
  374. will allow for indexing on a UDF. Descriptions may be up to 65 
  375. characters. This information is stored in a data base with an 
  376. extension .CS2. This file tags along with it's related (.CS1) 
  377. screen file and is not individually accessible via CodeSmith 
  378. except through the option menu.
  379.  
  380. If you select less that 15 indexes your application will provide 
  381. the option of creating a temp index. Index file names are the 
  382. first 6 characters of the database plus 1,2,. . .15. The number 
  383. of indexes chosen is stored in a public memvar. Your application 
  384. can then figure out if a temp index is available and if so make 
  385. use of it. The description for the temp index is it's key. 
  386. Selecting Re-Index from the application's main menu will index on 
  387. the header/key of the temp index, effectively the same as the 
  388. re-index command. All other indexes will be re-created since 
  389. their keys have been built into the application. The temp index 
  390. is real handy when you deliver an application and your customer 
  391. wants search by a new key.
  392.  
  393. Generate Full Application: Create a complete application.
  394.  
  395. Generate Code Fragment: 
  396. Produce @ SAYs and @ GETS based on your screen design, index keys 
  397. and descriptions plus procedures to create your database design 
  398. both in Summer '87 and 5.01. This comes in handy when you need to 
  399. make changes to an existing application, especially those that 
  400. are not created by CodeSmith.  
  401.  
  402.  
  403.                          QUICK TUTORIAL
  404.  
  405. From the DOS prompt type CS <Enter>.
  406.  
  407. Using the arrows keys, highlight SAMPLE.CS1 and press <Enter>.
  408.  
  409. At the next screen press <M> Main Menu.
  410.  
  411. Using the arrow keys, highlight Generate Full Application and 
  412. press <Enter>
  413.  
  414. At the prompt for the application name type SAMPLE and press 
  415. <Enter>.
  416.  
  417. Last prompt, select Network or Single User code. 
  418.  
  419. CodeSmith will now generate about 5,000 lines of 5.01 program 
  420. code.
  421.  
  422. When finished you see a prompt about compiling and linking the 
  423. application.
  424.  
  425. Press <ESC> twice,  then press <X> to Exit to DOS.
  426.  
  427. At the DOS prompt type GO SAMPLE.
  428.  
  429. GO.BAT will tell Rmake to process SAMPLE.MAK which will compile 
  430. all programs. Next it will tell SAMPLE.RMK to link the 
  431. application using RTlink. If you are using Blinker, you can REM 
  432. out the line calling RtLink.
  433.  
  434. Type SAMPLE <Enter>
  435.  
  436. Examine the application. 
  437.  
  438.                           OWN YOUR OWN
  439.  
  440. CodeSmith and it's applications support 25, 43 and 50 line 
  441. displays. The default for both is the current display mode. If 
  442. for example you are currently in 25 line mode and you want to 
  443. generate an application for 50 line VGA displays, use the <L> 
  444. setmode()/ Lines option. This will give you twice the screen area 
  445. to work with. The finished application defaults to the current 
  446. mode so begin application by typing SAMPLE 50.  
  447.  
  448. After doing the tutorial re-enter CodeSmith and experiment with 
  449. the supplied application design file provided, SAMPLE.CS1. Edit a 
  450. few fields to see their attributes. Add, modify and deleted 
  451. fields; move things around to get the feel of the screen painter. 
  452.  
  453. I have not guided you through the creation of an application from 
  454. scratch because I have found that after a few minutes of learing 
  455. to navigate around the screen, users of CodeSmith need very 
  456. little prompting. Normally when I give a demo of CodeSmith, I let 
  457. the user sit in the drivers seat and only spend a couple of 
  458. minutes explaining the theory of operation. Many of us (myself 
  459. included) would rather use the application than read (boring) 
  460. documentation (like this) so I have attempted to keep the product 
  461. easy to use and kept the paper work to a minimum. 
  462.  
  463. After playing with sample.cs1, start a new session by selecting 
  464. a .DBF file. Move things around to suit your taste and then 
  465. generate a full application. 
  466.  
  467. At first glance it may appear that CodeSmith has a lot of options 
  468. to deal with, but not really. With the exception of entering 
  469. INDEX KEYS, (you can't search without an index) the others can be 
  470. ignored. With a little practice you can create a full working 
  471. application in a few minutes while your customer watches. Now 
  472. your customer can begin data entry, impressed at how efficient 
  473. you are, while you return to your office and . . .
  474.  
  475. CodeSmith is intended to relieve you of the mundane aspects of 
  476. programming. I use it for all my simple applications and as a 
  477. starting point for complex applications.
  478.  
  479. When was the last time bought a valuable programming tool for 
  480. only $49.00 (regular price is $129.00) ?
  481.  
  482. CodeSmith is being actively developed with changes on a daily 
  483. basis. Future versions will include relations and user defined 
  484. pop-up validation functions, etc. Let me know what you need. 
  485.  
  486. The current (Christmas 1991) upgrade policy is 50% of the current 
  487. selling price. Beta testers get free upgrades. 
  488.  
  489. If you have any problems, please give me a call, I want you to be 
  490. productive. I welcome your comments and suggestions. 
  491.  
  492. Don Allred (818) 783-5837
  493.  
  494. Happy Programming!
  495. 
  496.